Inside Macintosh: Programming With the Text Encoding Conversion Manager /

Chapter 4 - Unicode Converter Reference / Unicode Converter Functions

Converting From Unicode to Multiple Encodings /

CreateUnicodeToTextRunInfoByEncoding

Based on the given text encoding specifications for the converted text runs, creates and returns a Unicode converter object containing information required for converting strings from Unicode to one or more specified non-Unicode encodings.

pascal OSStatus CreateUnicodeToTextRunInfoByEncoding (
      ItemCount iNumberOfEncodings,
      const TextEncoding iEncodings[],
      UnicodeToTextRunInfo *oUnicodeToTextInfo); 

iNumberOfEncodings

The number of desired encodings. If you pass 0 for this parameter, the converter will use all of the scripts installed in the system. The primary script is the one with highest priority; ScriptOrder('itlm' resource) determines the priority of the rest. If you set the high-order bit for this parameter, the Unicode converter assumes that the iEncodings parameter contains a single element specifying the preferred encoding. This feature is supported for versions 1.2 or later of the converter.

iEncodings

An array of text encoding specifications for the desired encodings. Your application provides this structure to identify the encodings to be used for the conversion. The order in which you specify the encodings determines the priority of the destination encodings. If you pass NULL for this parameter, the converter will use all of the scripts installed in the system. The primary script is the one with highest priority and
ScriptOrder('itlm' resource) determines the priority of the rest.This feature is supported for versions 1.2 or later of the converter.

oUnicodeToTextInfo

A pointer to a Unicode converter object for converting Unicode text strings to strings in one or more non-Unicode encodings. On output, a Unicode converter object that holds the encodings you supply as the iEncodings parameter and the state information related to the conversion.

function result

A result code. See "Text Encoding Conversion Manager Result Codes" (page 42) in the chapter "Basic Text Types Reference."

DISCUSSION

You pass a Unicode converter object returned from CreateUnicodeToTextRunInfoByEncoding to the function ConvertFromUnicodeToTextRun (page 150) or ConvertFromUnicodeToScriptCodeRun (page 155) to identify the information to be used for the conversion. These two functions modify the contents of the Unicode converter object.

In addition to various resource and memory errors, the function can return the following result codes:

• kTextUnsupportedEncodingErr
One of the encodings specified by the Unicode mapping structure you supply is not currently supported.
• kTECMissingTableErr
  A resource associated with one of the encodings is missing.
• kTECTableChecksumErr
  A resource has an invalid checksum, indicating that it has become corrupted.

If an error is returned, the converter object is invalid.